====== snap Plugin ======

---- plugin ----
description: Displays a site as a snapshot (fr: Affiche un site sous forme de miniature)
author     : Etienne M.
email      : emauvaisfr@yahoo.fr
type       : helper, syntax
lastupdate : 2008-10-17
compatible : 2008-05-05
depends    : 
conflicts  :
similar    :
tags       : media, images, links

downloadurl: http://emauvaisfr.free.fr/dokuwiki/snap.tar.gz
bugtracker :
sourcerepo :
donationurl: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=79ZVTRTJ52DDY&lc=FR&item_name=Plugin%20dokuwiki%20%28Etienne%20M%2e%29&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted
----

===== Description =====

  * helper: do the snapshot of a given URL (DokuWiki page ID or full URL). View [[#helper_reference|helper reference]].
  * syntax: calls the helper to insert a snapshot into your pages using an [[#syntax|easy syntax]].
  * French and English. It's easy to add you own language.


===== Requirements =====

  * This plugin will only work on Linux (not the plugin itself, but the snapshot server...)
    * The whole snap process was tested on a Debian distribution v.4.0.
    * Tell me if you make it work on a Windows box (or another)!
    * Use it at your own risks! ;-)
  * You must have root access to your DokuWiki server.
    * This may not be possible if your DokuWiki is hosted...

  * Software needed to do the snapshot:
    * ''html2image'': the tool that does the URL snapshot.
      * See http://www.guangmingsoft.net/htmlsnapshot/html2image.htm
    * ''Xvfb'': a virtual X server.
      * See [[wp>Xvfb]]
    * ''convert'': an image processing command from ''ImageMagick'', that allows to resize and crop images (and much more).
      * See http://www.imagemagick.org/script/convert.php

  * Software needed to set up the snap server:
    * ''netcat'': a small network software that does a lot of things, such as listen on a port and answer with a specified program.
      * See [[wp>Netcat]]

  * See [[#installation|this chapter]] for installation how-to.


===== How it works? =====

  * Some modules are needed to do the snapshot:
  - A snapshot server (''server.sh'')
    * It listens on one or more ports and sends the connections to the following script (using ''netcat'')
  - A script that does the snapshot (''snap.sh'')
    * It reads the parameters sent to the server and passes through the steps of the snapshot:
      * The snapshot itself (using ''html2image'')
      * The crop of the resulting image (using ''convert'')
      * Its resize (using ''convert'')
  - A helper (''helper.php'') that launches the snapshot by connecting the snapshot server and sending it the required parameters.
    * You can use this helper into your own plugins to use their functionality (See the [[#helper_reference|helper reference]]).
  - A plugin (''syntax.php'') that reads the [[#syntax|syntax]] to get the parameters and call the helper.

  * Why is it so complicated?!
    * Because when you try to call ''html2image'' directly from a PHP page, you get a ''pagination fault'' error.

  * After the snapshot, the snap image is available as a ''.jpg'' file on the hard drive (into ''./data/snap'' for example).
    * The name of this file keeps track of the URL that was "snapped" and the snap size (ex: ''start_300x200.jpg'')
    * A snap cache mechanism is used to avoid generating a snapshot over and over. If the snap is found on the drive, having the same dimensions and not too old (regarding ''$conf['cachetime']''), it is not generated again (unless you ask to force snapshot without using the cache (see [[#syntax|below]]))


===== Important =====

  * Be aware that people can read snap of pages they may not have right to access (this is due to snap caching). However, the snap is normally small enough to prevent a comfortable reading ;-)
  * If your DokuWiki is not open for reading to everyone (use of authentication), you must configure the helper to add login parameters to the URL to snap. See the ''helper.php'' file to do this right.
    * It is recommended to use [[:tips:phashlogin|this tip]] to avoid clear password into the URLs, but an password hash instead.
  * By now, the snap server and the DokuWiki server have to be on the same computer.
    * A next version will try to make it possible to have separate computers.
    * However, you can use a dedicated snap server if you do a filesystem mount to make the snap files available to your DokuWiki (not tested in the real world).
  * The version of ''html2image'' used by the snap server doesn't render the flash objects.

===== Installation =====

  * Given examples are valid for a Linux Debian v4.0 distribution.

==== html2image ====

  * As user ''root'', install ''html2image'' into ''/usr/lib/html2image'' for example (download it here: http://www.guangmingsoft.net/htmlsnapshot/html2image.htm)
  * Configure the proxy options into ''./html2image/greprefs/all.js''. Example :<code javascript>
pref("network.proxy.autoconfig_url",        "http://myProxy/myScript");
pref("network.proxy.type",                  2);
</code>
  * Add the line ''<path to html2image>'' (for example ''/usr/lib/html2image'') into the file ''/etc/ld.so.conf.d/html2image.conf'' (create it)
    * Run ''ldconfig'' to activate the changes.
    * If you don't want to modify this file, you will have to define the LD_LIBRARY_PATH variable each time you wish to use ''html2image''.

==== Xvfb ====

  * Verify if ''Xvfb'' is installed (''Xvfb -'' -> doit afficher la liste des options)
    * If not: ''apt-get install xvfb''
  * (Re)install the xfonts-base fonts (''apt-get remove xfonts-base; apt-get install xfonts-base'')

==== Test if html2image is working ====

  * Run ''Xvfb :1 -screen 0 640x480x24 -nolisten tcp -fp /usr/share/fonts/X11/misc&'' (provide another ''fp'' if your fonts are elsewhere (''fp=font path'')
  * Define the DISPLAY variable: ''export DISPLAY=:1''
  * Launch a snapshot: ''<nowiki>cd /usr/lib/html2image; ./html2image www.google.com /tmp/try.jpg</nowiki>''
  * -> Verify that the file ''/tmp/try.jpg'' exists and it contains a pretty snapshot
  * Stop Xvfb (''pkill Xvfb'')

==== netcat ====

  * Verify that ''nc'' is installed (''nc -h'' -> v1.10)
    * If not: ''apt-get install netcat''

==== convert ====

  * Verify that ''convert'' is installed (''convert -version'' -> v6.2.4)
    * If not: ''apt-get install imagemagick''
    * Help on convert: http://www.imagemagick.org/script/convert.php

==== snap plugin ====

  * Use the Plugin Manager to install the snap plugin (see download at the top of this page).

===== Configuration =====

  * Still as user ''root'':
    * Create this directory ''/var/www/wiki/data/snap'' (for example)
    * Give it the 777 rights (''chmod 777 /var/www/wiki/data/snap'')

  * You can go back to a "non ''root''" profile
  * Verify that the server parameters are correct (paths, ports, aso...) into ''/var/www/wiki/lib/plugins/snap/server.sh''
  * Launch the server: ''/var/www/wiki/lib/plugins/snap/server.sh &''
  * Verify that the plugin parameters are in phase with the server (see into ''/var/www/wiki/lib/plugins/snap/helper.php'')
  * Verify that the authentication method used by the helper fits your DokuWiki configuration.
    * See [[tips:phashlogin|this tip]] to allow phash password login into the URL (instead of a readable password).

==== Test ====

  * Add this into your playground page: <nowiki>{{[[start]]}}</nowiki>
  * -> The snapshot must appear.


===== Syntax =====

  * Like a link (''<nowiki>[[site_url]]</nowiki>'') changed into a picture (''<nowiki>{{picture_url}}</nowiki>'') -> ''<nowiki>{{[[site_url]]}}</nowiki>''
    * The site url can be a "normal" one ([[http://www.dokuwiki.org]]) or a DokuWiki page ID (''start'', ''fr:plugin:snap'', aso...)

  * Examples:
    * Basic: ''<nowiki>{{[[start]]}}</nowiki>'' or ''<nowiki>{{[[http://www.dokuwiki.org]]}}</nowiki>''\\ {{http://emauvais.multimania.com/dokuwiki/snap_start_200x150.jpg}} or {{http://emauvais.multimania.com/dokuwiki/snap_web_www.dokuwiki.org_200x150.jpg}}
    * Define width: ''<nowiki>{{[[start|150]]}}</nowiki>''\\ {{http://emauvais.multimania.com/dokuwiki/snap_start_150x113.jpg}}
    * Define height: ''<nowiki>{{[[start|x100]]}}</nowiki>''\\ {{http://emauvais.multimania.com/dokuwiki/snap_start_133x100.jpg}}
    * Define width and height: ''<nowiki>{{[[start|300x100]]}}</nowiki>''\\ {{http://emauvais.multimania.com/dokuwiki/snap_start_300x100.jpg}}
    * Don't use the snap cache (force snapshot): ''<nowiki>{{[[start|!]]}}</nowiki>''
    * Mixed: ''<nowiki>{{[[start|100!]]}}</nowiki>'' (100 px width and don't use snap cache)


===== Notes =====

  * The default snap size is 200x150 pixels.
  * There are also maxWidth and maxHeight parameters to avoid too big snaps (400x300).
  * When just width or height is provided, the plugin uses a 4/3 factor to calculate the missing dimension.
  * See ''helper.php'' to change those values, and others ([[#helper_reference|helper reference]]).

===== Helper reference =====

  * The getSnap() function is used to do the snapshot of a site.
    * Parameters:
      * URL to snap or DokuWiki page ID (required)
      * Snap width (optional)
      * Snap height (optional)
        * If no width and height are provided, uses the default dimensions (200x150).
        * If only the width or the height is provided, uses the ''imFactor'' parameter to calculate the missing dimension.
      * Use the snap cache (optional. Default is true.)
    * Returns an array with:
      * The path and name of the snapshot.
      * The page title (if a DokuWiki page id was submitted).
      * The target frame for the link to the "snapped" site.
    * All the snap object properties are also available (see below).

  * Usage example into a ''syntax'' plugin:<code php>
[...]
$snap=plugin_load('helper','snap');
if (!$snap) {
  $renderer->doc .= "<b>SNAP:</b> Snap helper not found<br />";
  return false;
}

list($imagePath, $pageTitle, $target)=$snap->getSnap($param, $width, $height, $checkCache);
if (!$snap->succeed || !$imagePath) {
  $renderer->doc .= "<b>SNAP:</b> Problem during the snap of $param<br />";
  return false;
}
[...]
</code>
  * <file>
helper_plugin_snap Object
(
    //Read/Write properties -----------------------------------------------------------------------------------------
    [defaultWiki] => http://myDokuwikiServer/wiki/doku.php?id=         //Base address used to snap DokuWiki page ID.
    [screenx] => 1280                                                  //Width of the virtual browser into which the snap is done.
    [screeny] => 1024                                                  //Height of the virtual browser into which the snap is done.
    [imFactor] => 1.33333333333                                        //width/height image proportion.
    [defLarg] => 200                                                   //Default width of the snaps.
    [defHaut] => 150                                                   //Default height of the snaps.
    [maxLarg] => 400                                                   //Max width allowed for the snaps.
    [maxHaut] => 300                                                   //Max height allowed for the snaps.
    [snapServer] => localhost                                          //Snap server address.
    [snapPorts] => 8888 8889 8890 8891 8892                            //Snap server port(s).
    [snapTimeout] => 5                                                 //Max duration for a snap (seconds).
    [tryTimeout] => 3                                                  //Max retries to connect snap server.
    [checkCache] => 1                                                  //Use snap cache (true/false).
    [width] => 200                                                     //Snap width.
    [height] => 150                                                    //Snap height.
    [outputPath] => /var/www/wiki/data/pages/../snap/                  //Directory to store the snaps.

    //Read only properties ------------------------------------------------------------------------------------------
    [imagePath] => /var/www/wiki/data/pages/../snap/start_200x150.jpg  //Path and name of the current snap.
    [titrePage] => My page title                                       //Page title (if a DokuWiki page ID was submitted).
    [snapTime] => 1224068749                                           //Snap time.
                                                                       //Can be different of the snap launch time if the snap was found into the cache.
    [snapTimeFormatted] => 15/10/2008 13:05                            //Formatted snap date (uses $conf['dformat']).
    [fromCache] =>                                                     //Snap found into the cache (true/false).
    [succeed] => 1                                                     //Snap successful (true/false).
    [target] =>                                                        //Target of the link (uses $conf['target']['extern'] and $conf['target']['wiki']).
    [selectedPort] => 8890                                             //Port used for this snap.
    [snapLog] => Width :1280                                           //Snap log (the password are hidden).
Height :1024
Time Out :5000
URL :http://myDokuwikiServer/wiki/doku.php?id=start&u=myLogin&phash=******
Output image :/var/www/wiki/data/pages/../snap/start_200x150.jpg
content size:1280X1281
Convert HTML to image succeeds
Resize 200
Crop 200x150+0+0
    [timeout] =>                                                       //Timeout detected during the snap (true/false).
    [snapDuration] => 2                                                //Snap duration (seconds).
    [snapTotalDuration] => 2                                           //Total duration (seconds).
                                                                       //Can be greater than the snap duration itself if more than one retry was done to connect the snap server.
    [tries] => 1                                                       //Tries to connect the snap server.
    [url] => http://myDokuwikiServer/wiki/doku.php?id=start            //"Snapped" page address.

    //Inherited properties ------------------------------------------------------------------------------------------
    [allowedModesSetup] =>
    [localised] => 
    [lang] => Array
        (
        )
    [configloaded] => 
    [conf] => Array
        (
        )
    [Lexer] => 
    [allowedModes] => Array
        (
        )
)
</file>


===== Version history =====

  * 2008-10-17: first one!


===== Discussion =====

  * Tell me...